Mock 服务部署：Vercel 与 Cloudflare
04 节留了个尾巴：mock server 是 Hono 写的常驻服务（SSE 流式接口），GitHub Pages 只支持静态页面跑不了它。这节把文档站 + mock server 一起部署到 Vercel，策略与前面一致——不改主分支、交给 AI 完成；文末给出 Cloudflare Workers 等替代方案的选型对比，可自行跑通。
选型：谁能跑常驻（Serverless）进程
把「Pages 跑不了后端，mock server 放哪」直接丢给大模型，它会给出候选清单。对照 2026-11-07 核实的免费额度（部署前自己再核一遍，各平台额度经常调整）：
| 平台 | 免费额度（2026-11-07 核实） | 关键限制 |
|---|---|---|
| Vercel Hobby | 100 GB Fast Data Transfer/月、1M 次函数调用/月、Fluid Active CPU 4 小时/月、100 次部署/天、单次构建 45 分钟上限 | 仅个人非商业项目；Hobby 项目不能连接组织（org）名下的 GitHub 仓库，仓库须在个人账号下；Pro $20/席/月 |
| Cloudflare Workers Free | 10 万请求/天、每次 10ms CPU；Pages 静态请求不限量 | 付费 $5/月升 1000 万请求/月 |
| Render | 免费实例 512 MB RAM（Hobby 计划 $0 + compute，最多 25 个服务） | 15 分钟无访问就休眠，冷启动 30-60 秒；付费 Web Service $7/月起 |
| Railway | 30 天试用送 5额度，之后Free档1/月（每服务 1 vCPU / 0.5 GB） | Hobby 5/月含5 用量额度 |
结论选 Vercel：文档站（静态）和 mock server（Serverless Functions）同一个项目、同一个平台部署，Hono 官方对 Vercel 有零配置支持和适配器，集成成本最低；免费额度对演示项目绰绰有余。Render/Railway 的免费层有冷启动，演示体验差。
不污染主分支：部署分支策略
集成 Vercel 会引入新依赖和入口文件，不想动主分支，就把「发布形态」隔离到独立分支。提示词（关键是把约束说死）：
> 我需要集成 Vercel 部署（文档站 + mock server），
> 但不想修改主分支上的代码或依赖项。
> 请创建一个专用于发布的单独分支，并规划整个集成方案。
text
AI brainstorm 依次确认三件事（照推荐选）：
- Vercel 上部署什么范围：文档站 + mock server 全选——Vercel 上都能跑，没必要拆两个项目
- 发布分支从哪里开：从 dev 开。日常开发都在 dev、领先 master 很多提交，从 dev 开才能带上最新功能（顺带可以把 dev 合回 master 完成一次发版）
- 发布分支怎么维护：长期分支 + merge 同步。建
deploy/vercel这类长期分支，dev 有更新就 merge 过来，不做「每次部署重建分支」的一次性方案
提问不打断主线：过程中遇到与当前任务无关的支线知识（比如 Vercel 某配置项的原理），在 Claude Code 会话里用 BTW（by the way）前缀去问，它不会污染当前绘制的上下文；Codex 里有类似的斜线 side quest。规划确认后，AI 自己开 subagent 团队并行完成集成开发。
Vercel 账号与 Token
- 注册登录：vercel.com → Log In → Continue with GitHub → 授权。之后 Vercel 也能直接 import 你 GitHub 账号下的仓库
- 创建 Token：右上头像 → Settings → 左侧 Tokens → Create Token：命名（如
DEVPUB）、Scope 选自己的账号或指定项目、有效期演示选 7 天 → Create → 复制 - 交给 AI（说明有效期 7 天）：
> 这是 Vercel 的 token（7 天有效期）。
> 请完成 Vercel 的整体集成开发与部署，并测试线上可用性。
text
拿到 token 后，创建项目、部署、绑域名、改配置全部由 AI 走 Vercel API 完成——第三方服务平台几乎都提供 token，拿到 token = 拿到该平台的 API 操作能力，这是 AI 代替人做部署的基础。和 npm token 同理：最小授权、短有效期、用完可撤销。
Hono × Vercel 集成
Hono 官方对 Vercel 是一等支持：pnpm create hono@latest my-app 选 vercel 模板即可起步；已有 Hono 应用接入只需两件套——api/ 目录入口 + vercel.json。
入口文件（monorepo 中复用 dev-server 的 Hono 实例，两种写法）：
// api/index.ts —— Vercel Serverless Function 入口
// 写法一：零配置默认导出（官方推荐），basePath 对齐 vercel.json 的 rewrites
import { Hono } from 'hono'
import app from '../src/app' // 复用现有 Hono 实例（已 export default app）
export default app // 如需统一前缀：new Hono().basePath('/api').route('/', app)
// 写法二：Node.js 运行时适配器（需要 Node API 时用）
// import { handle } from 'hono/vercel' // 或独立包 @hono/vercel（hono 4.x 同步发布）
// export default handle(app)
typescript
路由映射（来自 vercel/hono-starter 官方模板，逐字可抄）：
{
"rewrites": [
{ "source": "/api/(.*)", "destination": "/api" }
],
"redirects": [
{ "source": "/", "destination": "/api", "permanent": false }
]
}
json
命令行：
npm i -g vercel
vercel dev # 本地联调：模拟 Vercel 运行时起服务
vercel deploy # 部署到线上（alias: vc deploy）
bash
注意事项：mock server 里有 SSE 流式接口，Vercel 函数有执行时长上限（可通过 vercel.json 的 functions.api/index.ts.maxDuration 调高，上限随计划与运行时而定，以官方文档为准）；流式首包要在这个窗口内吐出去。
前端 API 地址：跟着环境走
部署完第一个问题：文档站里的 mock 演示、接口文档页请求的还是 localhost。原因是请求基地址写死了本地 dev-server。让地址按构建环境切换：
// 前端 API 配置（openapi.ts 等）
const API_BASE = import.meta.env.DEV
? 'http://localhost:8787' // 本地：pnpm dev 起的 dev-server
: '' // 线上：同域相对路径，走 /api/* 由 Vercel Functions 响应
typescript
改完重新部署，再点接口文档页的 Test Request → Send，响应就来自线上服务端地址（Network 面板可确认请求目标已是线上域名，不再是 localhost）。
国内访问与自定义域名
- 默认域名
*.vercel.app在大陆需要代理才能访问 - 绑定自定义域名：项目 → Settings → Domains → Add，填自己的域名或子域，按提示加 DNS 记录（CNAME 指向
cname.vercel-dns.com），验证生效后即可直连
线上验证清单
- 文档站 mock 演示页右侧状态显示**「已连接」**——线上 mock server 正常响应
- 接口文档页任选接口 Test Request → Send，返回正常响应且请求地址为线上域名
- SSE 流式对话演示逐字输出、可中断
到这里 mock server 的部署全部收尾，整个过程就三步：给出明确指令（含「不改主分支」等约束）→ 平台侧创建 token 给 AI → AI 自动完成集成、部署、调试。后编程时代，重复性的基础设施配置交给 AI，人专注业务本身。
Cloudflare Workers：第二个值得跑通的方案
同样的 Hono 代码迁到 Cloudflare Workers 改动极小，免费层每天 10 万请求对演示项目足够：
pnpm create hono@latest my-app # 模板选 cloudflare-workers
cd my-app && pnpm i
npx wrangler dev # 本地联调（wrangler 是 Cloudflare 官方 CLI）
npx wrangler deploy # 部署
bash
- Hono 本身就诞生于 Cloudflare Workers 生态，
app.fetch天然适配，SSE 流式响应在 Workers 上没有 Vercel 那种函数时长限制（受 CPU 时间约束） - 默认域名
*.workers.dev在大陆同样不稳定，正式使用绑自定义域名 - 国内云函数平台（阿里云函数计算、腾讯云 SCF 等）也有免费额度与 HTTP 触发器，可作为完全无代理的国内替代，用同样的「token + AI」三步法接入
第 14 章交付链路完整闭环：npm 发包（01-03）→ 文档站上线（04）→ mock 服务上线（05）。下一章进入服务端：agents 与 server 包、多模型支持。
↑